Skip to content

Clarify what --isolated allows for aspire run and aspire start - #2223

Merged
David Pine (IEvangelist) merged 2 commits into
microsoft:mainfrom
guru-bharadwaj20:docs/isolated-same-path
Nov 20, 2026
Merged

David Pine (IEvangelist) merged 2 commits into
microsoft:mainfrom
guru-bharadwaj20:docs/isolated-same-path

Conversation

@guru-bharadwaj20

Copy link
Copy Markdown
Contributor

Summary

Fixes #2184.

The --isolated text on the aspire run and aspire start pages said it lets "multiple instances of the same AppHost run simultaneously". The CLI doesn't allow that for a single AppHost path. Before it starts, it looks for a running instance of the same AppHost file and stops it, whether --isolated is set or not:

  • RunCommand calls FindAndStopRunningInstanceAsync and, in isolated mode, prints a warning that the running instance will be stopped and that you should run from a different directory, such as a git worktree.
  • AppHostLauncher.LaunchDetachedAsync, which backs aspire start and aspire run --detach, calls StopExistingInstancesAsync ("same behavior as regular run").

This PR changes both pages:

  • The option text now says what --isolated actually allows: copies of the same AppHost in different directories, such as Git worktrees, can run at the same time. A second paragraph says that running again from the same path stops the existing instance.
  • The isolated-mode example now uses a worktree, because running aspire run --isolated twice from one directory only replaces the first run.

microsoft/aspire#22344 tracks the same fix for the --help text. If that wording lands differently, I can update these pages to match.

Third-party links and affiliations

None

Validation

  • Read the run, start and detach code paths in microsoft/aspire to confirm the behavior described above.
  • Checked the added lines against .github/forbidden-words.json. Nothing matches.
  • Docs-only change. I didn't run a site build locally.

The option text said --isolated lets multiple instances of the same
AppHost run at once. The CLI stops an instance that is already running
from the same AppHost path, isolated or not, so concurrent runs need
separate directories such as Git worktrees. Spell that out and replace
the examples with a worktree example.

Fixes #2184

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@guru-bharadwaj20

Copy link
Copy Markdown
Contributor Author

@microsoft-github-policy-service agree

@IEvangelist David Pine (IEvangelist) left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docs accuracy review: --isolated on aspire run and aspire start

Verdict: COMMENT. I checked the changed text against the Aspire source and ran both examples. No claim is contradicted, and the doc-tester found no critical issues. Both new examples worked exactly as written with Aspire CLI 17.0.0. The suggestions below are non-blocking.

  • Source checked (Phase A): microsoft/aspire main @ f04f1cb430285efc2602335ab04055c088330bfd, which matches this PR's main target. I also checked release/17.0 @ 3999b4c0981f59f5e4877c248aa6a7a7ee4668b9, the release these docs currently describe. It stops same-path instances the same way and prints the same warning text. No claims involve Community Toolkit or Azure SDK code.
  • Claims (Phase A): I extracted 14:
    • 10 verified
    • 3 verified with nuance
    • 1 narrative
    • 0 unverifiable or contradicted
  • Doc-tester run (Phase B): I served the PR head (b5d05cd18655af1ef37a9790f516f6ea1590f22c) locally. The tester checked the --isolated option and the worktree example on /reference/cli/commands/aspire-run/ and /reference/cli/commands/aspire-start/. It then ran both examples literally with a file-based C# AppHost. Result: 0 critical issues and 6 warnings (3 Medium and 2 Low for the docs, 1 Medium for the product).

Suggested follow-ups (non-blocking)

  1. aspire-run.mdx L112: say which mode prints the warning. Only aspire run --isolated in the foreground prints it. aspire run --detach --isolated and aspire start --isolated also stop an instance on the same path, but print no warning. Both phases confirmed this. The sentence just before lists aspire run --detach, so readers will expect the warning there too. Suggested wording: "When it stops an instance this way, aspire run --isolated (without --detach) also prints a warning that suggests running from a different directory."
  2. aspire-run.mdx L171: say where the second terminal starts. cd ../my-app-feature only works from the main checkout. Suggested wording: "Then, in a second terminal opened in the main checkout:"
  3. Both examples: state the Git prerequisites. Readers need to know three things:
    • A worktree contains only committed files.
    • git worktree add ../my-app-feature also creates a my-app-feature branch.
    • If the repository has no commits, git 2.56 doesn't fail. It creates an empty orphan worktree, and aspire start there then fails because it finds no AppHost.
  4. aspire-start.mdx L144: add "From the repository's main checkout:". Optionally, add a cleanup step: run aspire stop in each directory, then git worktree remove ../my-app-feature.
  5. Optional: note how secrets behave in a worktree. It depends on the AppHost type:

FYI: The CLI help text for --isolated still says "allowing multiple instances to run simultaneously" (SharedCommandStrings.resx L195-L197). These docs are now more precise than --help, which is intentional. microsoft/aspire#22344 tracks fixing the help text, as the PR description says.

Phase A: claim verification

There are no inline comments, because no claim was contradicted or unverifiable. The changed lines contain no hard-coded Aspire versions (so no placeholder is needed) and no legacy project APIs.

Verified (10) and verified-with-nuance (3) claims, with evidence from microsoft/aspire@f04f1cb
ID Location Claim Verdict Evidence
A1 aspire-run.mdx L110 --isolated runs with randomized ports and isolated user secrets verified with nuance .NET AppHosts: isolated mode sets DcpPublisher__RandomizePorts=true and runs against a temporary copy of the project's .NET user-secrets file (DotNetAppHostProject.cs L1539-L1555, L2788-L2811). TypeScript (guest) AppHosts: only ports are randomized (GuestAppHostProject.cs L626-L629). Their secrets ID already comes from the AppHost path (L651-L652).
A2 aspire-run.mdx L110 Copies of the same AppHost in different directories, such as Git worktrees, can run at the same time verified The CLI finds running instances by a hash of the normalized AppHost file path (AppHostSocketManager.cs L105-L118, BackchannelConstants.cs L116-L140), so it never stops a copy at a different path. Randomized ports prevent port conflicts. The CLI's own warning gives the same advice: "run from different directories such as git worktree directories" (RunCommandStrings.resx L261-L263).
A4 aspire-run.mdx L112 --isolated doesn't allow multiple instances from the same AppHost path verified RunCommand.cs L341-L349, AppHostLauncher.cs L223-L224
A5 aspire-run.mdx L112 aspire run stops an instance already running from the same path before it starts, with or without --isolated verified FindAndStopRunningInstanceAsync always runs before the new run starts, whether or not --isolated is set (RunCommand.cs L341-L349, DotNetAppHostProject.cs L2607-L2626, GuestAppHostProject.cs L2049-L2079). It doesn't prompt; it prints "Stopping previous instance (AppHost PID: ..., CLI PID: ...)" (RunningInstanceManager.cs L48-L68).
A6 aspire-run.mdx L112 aspire run, aspire run --detach, and aspire start all behave this way verified aspire run --detach calls LaunchDetachedAsync (RunCommand.cs L217-L219, L1489-L1531), and so does aspire start (StartCommand.cs L128-L139). That method calls StopExistingInstancesAsync before it launches the AppHost; the code comment says "same behavior as regular run" (AppHostLauncher.cs L223-L224, L324-L338).
A7 aspire-run.mdx L112 When it stops an instance, aspire run --isolated prints a warning suggesting a different directory verified with nuance The warning is printed at RunCommand.cs L351-L355; the text is at RunCommandStrings.resx L261-L263. It appears only for a foreground run, and only after the stop succeeds. With --detach or aspire start, the launcher stops the instance itself (AppHostLauncher.cs L324-L338) and prints only "Stopping previous instance...". Phase B reproduced this; see the C4 table. Fix: follow-up 1.
A8 aspire-run.mdx L164-L176 Worktree example: run aspire run --isolated in the main checkout and again in ../my-app-feature verified The evidence for A2 applies. aspire.config.json stores the AppHost path relative to the config file (ProjectLocator.cs L1341), so a committed config in the worktree points to the worktree's own AppHost. Phase B ran the example as written (C3).
B1 aspire-start.mdx L108 --isolated runs with randomized ports and isolated user secrets verified with nuance Same as A1. aspire start passes --isolated through to the background aspire run process it launches (AppHostLauncher.cs L348-L367).
B2 aspire-start.mdx L108 Copies of the same AppHost in different directories can run at the same time verified Same as A2. Phase B ran this (C1).
B3 aspire-start.mdx L110 --isolated doesn't allow multiple instances from the same AppHost path verified AppHostLauncher.cs L223-L224
B4 aspire-start.mdx L110 aspire start stops an instance already running from the same path before it starts, with or without --isolated verified StopExistingInstancesAsync runs before the AppHost is launched and ignores --isolated (AppHostLauncher.cs L221-L229, L324-L338). Phase B confirmed this (C2).
B5 aspire-start.mdx L110 aspire run, aspire run --detach, and aspire start all behave this way verified Same as A6.
B6 aspire-start.mdx L144-L151 The worktree example can be run line by line in one terminal verified aspire start waits until the AppHost is running and then exits (AppHostLauncher.cs L241-L247), so the next line can run. Phase B ran it as written (C1).

The narrative claim (A3, "useful for parallel testing or comparing different configurations side-by-side") has nothing in the source to check.

Phase B: doc-tester results

I left out local environment and cleanup details, plus incidental notes about unchanged sections that are outside this review's scope. The rest is the tester's report.

Documentation Test Report

Focus Area: The --isolated option and its example on the aspire run and aspire start CLI reference pages (aspire.dev PR #2223).
Date: 2026-11-20
Tester: doc-tester agent (Phase B, without access to the Aspire source)

Context
  • Pages tested:

    • /reference/cli/commands/aspire-run/: the --isolated option and examples 6-7 of 8
    • /reference/cli/commands/aspire-start/: the --isolated option and example 4 of 5

    I served both from a local Astro dev server at b5d05cd18655af1ef37a9790f516f6ea1590f22c.

  • Tools: Aspire CLI 17.0.0+2d325b13709752ba6d9a943635c5e2940a2530c0, .NET SDK 10.0.404, git 2.56.1, on Windows.

  • Test project: created with aspire new aspire-empty --language csharp -n MyApp -o my-app --suppress-agent-init --use-config-source false --non-interactive. The --use-config-source false flag was needed only because of a local machine setting. This gives a file-based apphost.cs (#:package Aspire.Hosting.AppHost@17.0.0), plus apphost.run.json, aspire.config.json, and .vscode/extensions.json. It doesn't create a .gitignore.

  • Setup changes:

    • I set "launchBrowser": false in apphost.run.json. This doesn't affect the behavior under test.
    • I ran git init, git add -A, and git commit -m "Initial commit".
  • Prompts: aspire run and aspire start never needed --non-interactive.

Summary
Category Passed Failed Warnings
Content Accuracy 9 0 2
Code Examples 2 0 3
CLI Commands 8 0 1
Links / Rendering 3 0 0
Critical Issues

None. Every claim in the changed text matched what the CLI did, and both examples worked when followed literally. They do rely on the unstated assumptions listed under Warnings.

Warnings
Warning 1: The second terminal's starting directory isn't stated (Medium)

Location: aspire-run Examples: "Then, in a second terminal:" followed by cd ../my-app-feature
Issue: cd ../my-app-feature only works if the second terminal opens in the main checkout. Most new terminals open in the home directory. I had to assume the second terminal started in the main checkout.
Suggestion: "Then, in a second terminal opened in the same main checkout directory:".

Warning 2: Git prerequisites and worktree contents aren't mentioned (Medium)

Location: Both examples (git worktree add ../my-app-feature)
Issue: The examples assume the AppHost is in a Git repository with at least one commit.

  • With no commits, git 2.56.1 doesn't fail. It prints No possible source branch, inferring '--orphan' and creates an empty worktree that contains only .git.
  • aspire start --isolated in that empty worktree then fails with ❌ The --apphost option was not specified and no AppHost project files were detected. (exit code 7).
  • A worktree contains only committed files. Uncommitted, untracked, and ignored files are missing.
  • The command also creates a new branch named my-app-feature. Neither page says so.

Suggestion: Add a short prerequisite note and link to the git-worktree documentation.

Warning 3: The warning sentence suggests more than the CLI does (Low)

Location: aspire-run Options: "When it stops an instance this way, aspire run --isolated also prints a warning that suggests running from a different directory."
Issue: The warning appears only for aspire run --isolated in the foreground. aspire run --detach --isolated and aspire start --isolated also stop an instance on the same path but print no warning. The sentence before it lists aspire run --detach, so readers will likely expect the warning there too.
Suggestion: "aspire run --isolated (without --detach)". Consider quoting the warning text (see C4).

Warning 4: A worktree copy has its own AppHost secrets (Medium)

Location: Both --isolated options ("isolated user secrets") and both examples
Issue: aspire secret path reports a different store for each directory: ~\.aspire\secrets\apphost-5da6…\Development.json in the main checkout and ~\.aspire\secrets\apphost-f424…\Development.json in the worktree. I ran aspire secret set Parameters:demo hello-from-main in the main checkout. It appeared in aspire secret list there, but not in the worktree. A copy that needs parameters or secrets will be missing them. I verified this only for a file-based C# AppHost.
Suggestion: Note that you must set secrets again in the worktree, and link to the secrets documentation.

Warning 5: The aspire-start example doesn't say where to run it or how to clean up (Low)

Location: aspire-start Examples: "Start two copies of the same AppHost side by side…"
Issue:

  • Unlike the aspire run example, it doesn't say "In the repository's main checkout".
  • It doesn't say how to stop both background copies or remove the worktree. When I ran aspire stop with no arguments from the worktree, it stopped only the worktree copy.

Suggestion: Add "From the repository's main checkout:". Add a cleanup step: run aspire stop in each directory, then git worktree remove ../my-app-feature.

Warning 6: The CLI help text contradicts the new docs (Medium, product)

Location: aspire run --help and aspire start --help
Issue: Both still say "Run in isolated mode with randomized ports and isolated user secrets, allowing multiple instances to run simultaneously". For the same path, the new docs say the opposite, and the docs match what the CLI does.
Suggestion: Fix the product: change the help text to say "copies of the same AppHost in different directories".

Passed Checks
  • Rendering and links: Both pages render without a Vite error overlay, and the #options and #examples anchors exist. The changed sections contain no links. The only console error is 404 … /api/live/ and a WebSocket warning. They also appear on the unchanged /reference/cli/commands/aspire-ps/ page, so they come from the dev environment, not this PR.

  • Version placeholders: The changed lines in aspire-run.mdx (L108-L112 and L164-L176) and aspire-start.mdx (L106-L110 and L144-L151) contain no Aspire versions.

  • C1: the aspire-start example, run exactly as written in one terminal from the main checkout:

    1. aspire start --isolated → Dashboard: https://localhost:49180/…, PID: 13192, ✅ AppHost started successfully.
    2. git worktree add ../my-app-feature → HEAD is now at a6ccebd Initial commit
    3. cd ../my-app-feature, then aspire start --isolated → Dashboard: https://localhost:51638/…, PID: 15356

    aspire ps then listed both as running: my-app-feature\apphost.cs │ 15356 │ :51638 and my-app\apphost.cs │ 13192 │ :49180. Both dashboards returned HTTP 302. Neither uses the launch profile's fixed port (17136), so the ports are randomized.

  • Extra check without --isolated: While the main copy ran on port 17136 after a plain aspire start, aspire start in the worktree failed with AddressInUseException … Dashboard endpoint 'https' configured: https://localhost:17136, ❌ AppHost process exited (exit code 2). Running copies from different directories needs --isolated.

  • C2: running aspire start again from the same path:

    • aspire start --isolated in the main checkout printed 🛑 Stopping previous instance (AppHost PID: 13192, CLI PID: 66248) and ✅ Running instance stopped successfully. It then started PID 69356 on port 62524.
    • aspire start with no flag replaced PID 69356 the same way and started on port 17136.
    • Neither printed the 🚨 warning. The worktree copy (PID 15356) kept running both times.
  • C3: the aspire-run example:

    • Terminal 1 (main checkout): git worktree add ../my-app-feature, then aspire run --isolated. It printed 🔑 Copying user secrets for isolated mode... and served the dashboard on port 63940.
    • Terminal 2 (assumed to start in the main checkout): cd ../my-app-feature, then aspire run --isolated. The dashboard used port 49563.

    aspire ps showed both running (PIDs 23348 and 34548).

  • C4: running aspire run variants again from the same path. The worktree copy (PID 34548) was unaffected every time.

    Already running (same path) New command Old instance stopped? 🚨 warning?
    run --isolated (T1) run --isolated (T3) Yes; T1 exited with code 0 and printed nothing Yes
    run --isolated (T3) run Yes No
    run (T4) run --detach Yes No
    run --detach run --detach --isolated Yes No
    run --detach --isolated run --isolated (T5) Yes Yes
    run --isolated (T5) start --isolated Yes No

    The exact warning text:

    🚨 A running instance of this AppHost was found and will be stopped. To run multiple isolated instances simultaneously, run from different directories such as git worktree directories.

    This confirms three claims: --isolated "doesn't enable multiple concurrent instances from the same AppHost path"; the CLI "stops it … with or without --isolated"; and "aspire run, aspire run --detach, and aspire start all behave this way".

Recommendations
  1. Priority fixes: None are critical. Warnings 1, 2, 3, and 5 offer optional wording fixes.
  2. Documentation gaps:
    • Git prerequisites and what a worktree contains (Warning 2).
    • Secrets are separate per directory (Warning 4).
    • One sentence on why copies conflict without --isolated: both use the launch profile's fixed ports.
  3. Product issues:
    • The --help text (Warning 6).
    • The 🚨 warning says "will be stopped", but it prints after ✅ Running instance stopped successfully.
    • A replaced foreground aspire run exits with code 0 and prints nothing.
    • Only a foreground aspire run --isolated prints the warning.
Knowledge Gaps
Knowledge Gap: Git worktrees and the term "main checkout"

What I needed to know: That git worktree add creates a sibling folder and a new branch from HEAD, that the folder contains only committed content, and that "main checkout" means the original working tree.
Source of my knowledge: My own prior knowledge, not the documentation.
User impact: Developers who don't use Git worktrees.
Recommendation:

  • Add a one-sentence explanation and link to the git-worktree docs.
Knowledge Gap: Where the second terminal starts

What I needed to know: That the second terminal must start in the main checkout.
Source of my knowledge: An assumption, not the documentation.
User impact: Anyone whose new terminals open in their home directory.
Recommendation:

  • Add an explanation to this page.
Knowledge Gap: What "isolated user secrets" means

What I needed to know: What isolated user secrets means in practice.
Source of my knowledge: My prior knowledge of .NET user secrets, not the documentation. The only related output was 🔑 Copying user secrets for isolated mode....
User impact: Readers can't tell which secrets a worktree copy will see.
Recommendation:

  • Clarify on this page and link to the secrets docs.
Knowledge Gap: Why copies conflict without --isolated

What I needed to know: That apphost.run.json fixes the ports, so two copies collide unless the ports are randomized.
Source of my knowledge: My prior knowledge, which the error above confirmed.
User impact: Without this, readers can't tell what --isolated adds.
Recommendation:

  • Add one sentence.

- Note that only aspire run --isolated without --detach prints the
  stop warning.
- Say that a worktree contains only committed files.
- Say where the second terminal and the aspire start example begin.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@guru-bharadwaj20

Copy link
Copy Markdown
Contributor Author

Thanks for testing this so thoroughly, and for pushing the fixes. The --detach point and the worktree notes make it a lot clearer.

@IEvangelist
David Pine (IEvangelist) merged commit 61a3400 into microsoft:main Nov 20, 2026
20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clarify worktree and same-path behavior for --isolated in the CLI reference

3 participants